KCCreateKeychain

KCCreateKeychain
Header:	Keychain.h		Carbon status:	Under Evaluation

Creates a new keychain.

OSStatus KCCreateKeychain (
    StringPtr password, 
    KCRef *keychain
);

password: A pointer to a Pascal string representing the password string which will be used to protect the new keychain. If you pass NULL, the Keychain Setup dialog box will be displayed to obtain it.
keychain: A pointer to a reference to the keychain you wish to create. If you pass a NULL pointer, KCCreateKeychain creates the new keychain in the Keychains folder. If you pass a valid reference pointing to NULL, the Keychain Manager allocates the memory for the keychain reference and returns it in this parameter. In this case, the keychain will be created in the Keychain folder.

function result: A result code. The result code errKCUserCanceled indicates that the user pressed the Cancel button in the create keychain. The result code errKCDuplicateKeychain indicates that the user tried to create a keychain which already exists. The result code errKCCreateChainFailed indicates that the attempt to create a keychain failed. The result code errKCInvalidKeychain indicates that the specified keychain is invalid. Additional errors may be returned if the keychain could not be created (for example, a file system or network error may be returned if there is no write access to the storage media).

DISCUSSION

The KCCreateKeychain function creates a new empty keychain optionally defined by the keychain and password parameters. If the specified keychain reference is NULL or points to NULL, the new keychain will be created in the Keychains folder within the Preferences folder of the System folder. If you pass a keychain reference whose location is unspecified or invalid, the Keychain Manager will fill in the location to the Keychains folder. If the Keychain Manager uses UI to create a keychain, that keychain is automatically unlocked after creation.

SPECIAL CONSIDERATIONS

The memory that the keychain reference occupies must be released by calling the function KCReleaseKeychain when you are finished with it.

VERSION NOTES

Available beginning with Keychain Manager 1.0. In Keychain Manager 1.0, the kccreatekeychain function provides the same functionality as KCCreateKeychain. In Keychain 2.0, you should use KCCreateKeychain, since kccreatekeychain is provided for convenience only and may be removed from the header file at some point in the future.

AVAILABILITY

Under evaluation for Carbon. Available in CarbonLib 1.0 and later when KeychainLib 1.0 or later is installed. Exported by CarbonLib 1.0 and later and by KeychainLib 1.0 and later.